<!DOCTYPE html>
<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8">

	<title>Bespin Plugin Guide</title>

	<link rel="stylesheet" type="text/css" href="../css/reset.css">
	<link rel="stylesheet" type="text/css" href="../css/stylesheet.css" media="screen,projection">
	<link rel="stylesheet" type="text/css" href="../css/colorful.css">
</head>
<body>

<!-- MAIN CONTAINER -->
<div id="main-container">

<!-- MENU -->
<ul id="menu">
	<li><a href="../index.html" title="Home">Home</a></li>
	<li><a href="../userguide/index.html" title="User Guide">Using Bespin</a></li>
	<li class="current"><a href="../pluginguide/index.html" title="Plugin Guide">Creating Plugins</a></li>
	<li><a href="../embedding/index.html" title="Embedding Bespin in your app">Embedding</a></li>
	<li><a href="../devguide/index.html" title="Developer's Guide">Developing Bespin</a></li>
</ul>
<!-- / MENU -->

<h1 id="web-title">Bespin Plugin Guide</h1>
<h2 id="web-subtitle">Editor API</h2>

<!-- INDEX PAGE -->

<!-- MAIN COLUMN -->
<div id="maincol">
<h2>Introduction</h2>
<p>The Bespin editor provides various functions for interaction. If you have the
environment (env) variable you can access the current editor via</p>
<div class="codehilite"><pre><span class="kd">var</span> <span class="nx">editor</span> <span class="o">=</span> <span class="nx">env</span><span class="p">.</span><span class="nx">editor</span><span class="p">;</span>
</pre></div>


<p>For example, a basic command function looks like this:</p>
<div class="codehilite"><pre><span class="nx">exports</span><span class="p">.</span><span class="nx">upperCaseCommand</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">env</span><span class="p">,</span> <span class="nx">args</span><span class="p">,</span> <span class="nx">request</span><span class="p">)</span> <span class="p">{</span>
    <span class="c1">// Get the editor instance from the environment variable.</span>
    <span class="kd">var</span> <span class="nx">editor</span> <span class="o">=</span> <span class="nx">env</span><span class="p">.</span><span class="nx">editor</span><span class="p">;</span>
    <span class="c1">// Replace the selected text with the current selected text, where</span>
    <span class="c1">// the current selected text is transformed to upper case.</span>
    <span class="nx">editor</span><span class="p">.</span><span class="nx">selectedText</span> <span class="o">=</span> <span class="nx">editor</span><span class="p">.</span><span class="nx">selectedText</span><span class="p">.</span><span class="nx">toUpperCase</span><span class="p">();</span>
<span class="p">};</span>
</pre></div>


<h2>Setter &amp; Getter API</h2>
<dl>
<dt><br></dt>
<dt>get editor.focus</dt>
<dd>returns true if the editor has the focus, false otherwise.</dd>
<dt>set editor.focus = <code>hasFocus</code></dt>
<dd>if <code>hasFocus</code> is true, the editor is focused, otherwise the editor loses focus.</dd>
<dt>get editor.readOnly</dt>
<dd>returns true if the editor is readOnly, false otherwise.</dd>
<dt>set editor.readOnly = <code>isReadOnly</code></dt>
<dd>if <code>isReadOnly</code> is true, the editor's content can't get changed, otherwise it can.</dd>
<dt>get editor.selection</dt>
<dd>returns the currently selected range.</dd>
<dt>set editor.selection = <code>newRange</code></dt>
<dd>sets the currently selected range to.</dd>
<dt>get editor.selectedText</dt>
<dd>returns the currently selected text.</dd>
<dt>set editor.selectedText = <code>newText</code></dt>
<dd>replaces the current selected text with <code>newText</code> and moves the cursor at the end of <code>newText</code>.
Returns true if the change was performed, otherwise false.</dd>
<dt>get editor.value</dt>
<dd>returns the current text.</dd>
<dt>set editor.value = <code>newValue</code></dt>
<dd>sets the value of the current text. Returns true if the change was performed,
otherwise false.</dd>
<dt>get editor.syntax</dt>
<dd>returns the initial syntax highlighting context (i.e. the language).</dd>
<dt>set editor.syntax = <code>newSyntax</code></dt>
<dd>sets the initial syntax highlighting context (i.e. the language).</dd>
</dl>
<h2>Function API</h2>
<dl>
<dt><br></dt>
<dt>editor.replace(<code>range</code>, <code>newText</code>, <code>keepSelection</code>)</dt>
<dd>replaces the range of text with newText. If keepSelection is true, the
current selection is maintained otherwise the cursor will jump to the end
of <code>newText</code>. Returns true if the change was performed, otherwise false.</dd>
<dt>editor.setCursor(<code>newPosition</code>)</dt>
<dd>moves the cursor to <code>newPosition</code>.</dd>
<dt>editor.setLineNumber(<code>lineNumber</code>)</dt>
<dd>scrolls and moves the cursor to the given <code>lineNumber</code>.</dd>
<dt>editor.getText(<code>range</code>)</dt>
<dd>returns the text within <code>range</code>.</dd>
<dt>editor.changeGroup(<code>func</code>)</dt>
<dd>performs <code>func</code> within one change group. This means, that all the actions
performed by <code>func</code> result in one undo/redo action. Returns true if the change
was performed, otherwise false.</dd>
</dl>
<p>Example:</p>
<div class="codehilite"><pre><span class="nx">editor</span><span class="p">.</span><span class="nx">changeGroup</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">editor</span><span class="p">)</span> <span class="p">{</span>
   <span class="nx">editor</span><span class="p">.</span><span class="nx">value</span> <span class="o">=</span> <span class="s1">&#39;Hello&#39;</span><span class="p">;</span>
   <span class="nx">editor</span><span class="p">.</span><span class="nx">selectedText</span> <span class="o">=</span> <span class="s1">&#39; World&#39;</span><span class="p">;</span>
<span class="p">});</span>
</pre></div>


<p>These are two performed actions, but as they are grouped as one change and
are one change in the undo/redo manager.</p>
<h2>Events</h2>
<p>Listening to events work like this:</p>
<div class="codehilite"><pre><span class="nx">editor</span><span class="p">.</span><span class="nx">selectionChanged</span><span class="p">.</span><span class="nx">add</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">newSelection</span><span class="p">)</span> <span class="p">{</span>
    <span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">&#39;selectionChanged&#39;</span><span class="p">,</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">(</span><span class="nx">newSelection</span><span class="p">));</span>
<span class="p">});</span>
</pre></div>


<dl>
<dt>editor.textChanged: (oldRange, newRange, newText)</dt>
<dd>Fired whenever the value changed.</dd>
<dt>editor.selectionChanged: (newSelection)</dt>
<dd>Fired whenever the selection changed.</dd>
</dl>
</div>
<!-- / MAIN COLUMN -->

<!-- SIDEBAR -->
<div id="sidebar">




<h2 class="compact">Contents</h2>
<ul class="compact">
<li><a href="index.html">Introduction</a></li>
<li><a href="distributing.html">Distributing Plugins</a></li>
<li><a href="editorapi.html">Editor API</a></li>
<li><a href="testing.html">Automated Testing</a></li>
<li><a href="template.html">Templates</a></li>
<li><a href="theme.html">Themes</a></li>
<li><a href="syntax.html">Syntax Highlighting</a></li>
<li><a href="keymapping.html">Keymapping</a></li>
</ul>







</div>
<!-- / SIDEBAR -->

<!-- / MAIN CONTAINER -->
</div>

<!-- FOOTER -->
<div id="footer">
	<!-- COLUMN ONE -->
	<div>
	<h2 class="compact">Useful Links</h2>
	<ul class="compact">
		<li><a href="http://mozillalabs.com/bespin/">Bespin project home page</a></li>
		<li><a href="https://wiki.mozilla.org/Labs/Bespin">Wiki</a></li>
	</ul>
	</div>
	<!-- / COLUMN ONE -->

	<!-- COLUMN TWO -->
	<div>
	<h2 class="compact">Developer Resources</h2>
	<ul class="compact">
	  <li><a href="http://hg.mozilla.org/labs/bespinclient/">Main Code Repository</a></li>
	  <li><a href="http://hg.mozilla.org/labs/bespinserver/">Python server repository</a></li>
		<li><a href="http://groups.google.com/group/bespin-core/">bespin-core mailing list for developers</a></li>
		<li><a href="http://groups.google.com/group/bespin-commits/">bespin-commits mailing list for repository commit messages</a></li>
		<li><a href="https://bugzilla.mozilla.org/buglist.cgi?product=bespin">Bug List</a></li>
	</ul>
	</div>
	<!-- / COLUMN TWO -->

	<!-- COLUMN THREE -->
	<div>
	<h2 class="compact">Get Help</h2>
	<ul class="compact">
		<li>The <a href="http://groups.google.com/group/bespin/">Bespin mailing list</a></li>
		<li>Via IRC: <a href="irc://irc.mozilla.org/bespin">#bespin on irc.mozilla.org</a></li>
	</ul>

	<h2 class="compact">Documentation Template</h2>
	<ul class="compact">
		<li>Adapted from a design by <a href="http://www.mgrabovsky.is-game.com/">Matěj Grabovský</a></li>
	</ul>
	</div>
	<!-- / COLUMN THREE -->
</div>
<!-- / FOOTER -->

</body>
</html>